With the strategic value of APIs in the enterprise, adopting DevOps continuous integration (CI) and deployment (CD) techniques has become an important aspect of API development. This article discusses the decisions you'll need to make to adopt DevOps principles for the management of APIs.

API DevOps consists of three parts:

Each part of the API DevOps pipeline is discussed below.

An API developer writes an API definition by providing a specification, settings (such as logging, diagnostics, and backend settings), and policies to be applied to the API. The API definition provides the information required to provision the API on an Azure API Management service. The specification may be based on a standards-based API specification (such as WSDL, OpenAPI, or GraphQL), or it may be defined using the Azure Resource Manager (ARM) APIs (for example, an ARM template describing the API and operations). The API definition will change over time and should be considered "source code". Ensure that the API definition is stored under source code control and has appropriate review before adoption.

There are several tools to assist producing the API definition:

You can also use IDE-based tools for editors such as Visual Studio Code to produce the artifacts necessary to define the API. For instance, there are over 30 plugins for editing OpenAPI specification files on the Visual Studio Code Marketplace. You can also use code generators to create the artifacts. The CADL language lets you easily create high-level building blocks and then compile them into a standard API definition format such as OpenAPI.

Once the API definition has been produced, the developer will submit the API definition for review and approval. If using a git-based source code control system (such as GitHub or Azure Repos), the submission can be done via Pull Request. A pull request informs others of changes that have been proposed to the API definition. Once the approval gates have been confirmed, an approver will merge the pull request into the main repository to signify that the API definition can be deployed to production. The pull request process empowers the developer to remediate any issues found during the approval process.

Both GitHub and Azure Repos allow approval pipelines to be configured that run when a pull request is submitted. You can configure the approval pipelines to run tools such as:

Note

Azure APIs must conform to a strict set of guidelines that you can use as a starting point for your own API guidelines. There is a Spectral configuration for enforcing the guidelines.

Once the automated tools have been run, the API definition is reviewed by the human eye. Tools won't catch all problems. A human reviewer ensures that the API definition meets the organizational criteria for APIs, including adherence to security, privacy, and consistency guidelines.

The API definition will be published to an API Management service through a release pipeline. The tools used to publish the API definition depend on the tool used to produce the API definition:

Can I use other source code control and CI/CD systems?

Yes. The process described works with any source code control system (although APIOps does require that the source code control system is git based). Similarly, you can use any CI/CD platform as long as it can be triggered by a check-in and run command line tools that communicate with Azure.

There's no industry standard for setting up a DevOps pipeline for publishing APIs, and none of the tools mentioned will work in all situations. However, we see that most situations are covered by using a combination of the following tools and services:

We've seen the greatest success in customer deployments, and recommend the following practices:

Review Automated API deployments with APIOps in the Azure Architecture Center for more details on how to configure and run a CI/CD deployment pipeline with APIOps.